fix(workbook): make the zoned and sparkline wire forms canonical-only - #774

closes #768

Summary

The published JSON schema had no branch for zoned and none for sparkline, so a workbook containing either serialized correctly and then failed validation against our own schema. A consumer doing the right thing was told the file was malformed.

Fixing it turned out to be less about the schema than about the wire reader.

The root cause is one thing, not five

The wire reader reuses parsers written for the formula level, where leniency is required, and inherits leniency the writer never exercises.

=SPARKLINE({1,2},{"charttype","LINE"}) must work in Sheets, so SparklineChartType::parse is case-insensitive. But from_json reusing it meant the wire accepted {"charttype":"Line"} — bytes our serializer never emits. The evidence that this was unintended sits eight lines away in the same function: the reader already rejects a non-lower-case option key.

Same story for zoned: core's parse_rfc9557 trims, because TZPARSE operates on user-typed arguments. The wire inherited that and accepted "…Z\n".

So the reader was tightened, not the schema widened, in both places. Widening instead would have documented junk as a valid document shape, which is the opposite of what a published contract is for. Core's formula-level parsers are untouched — only from_json got stricter.

⚠️ This narrows what from_json accepts

Documents with a non-canonical charttype casing, or a whitespace-padded zoned value, now fail to load. Both are unreachable from our serializer, and SPARKLINE shipped a day ago, so nothing in the wild carries either. It is safe now and gets harder every day — worth flagging as a deliberate compatibility decision rather than a silent one.

Three gaps beyond the two the issue named

1. Both variants are reachable inside a spill anchor's array. ={TZNOW("UTC"),TZNOW("Europe/Berlin")} recalcs to an array of them, and scalarValue was missing both — so fixing only the top-level branches would have left whole documents failing.
2. The serializer emitted bytes nothing could read. to_json succeeded on a 0- or 1-point sparkline; both the schema and from_json reject those, breaking the crate's own round-trip guarantee. Now guarded at serialization time via S::Error::custom, mirroring what Value::Array already does eight lines up. Extended to upper-case option keys and a charttype option too — all three were constructible on a public struct and all three produced unreadable bytes.
3. The zoned pattern didn't bound field ranges. "2026-99-99T99:99:99+99:99" validated. Now bounded, including leap second :60 (which the reader accepts and normalizes) and the offset's true ±23:59.

The branches were derived from bytes, not from the enum

Values were serialized and the output read back. That caught a detail an eyeballed schema gets wrong: the bracketed zone is present for an IANA zone (…+01:00[Europe/Berlin]) and absent for a fixed offset.

The durable part is the test, not the branches

crates/workbook/tests/schema_value_variant_tests.rs validates serializer output against the schema for every Value variant, with two independent coverage gates — an exhaustive match (compile-time) and a runtime check parsing the variant list out of src/value.rs. Two hand-added branches without it would just reset the clock.

It was mutated, not asserted. Adding a hypothetical variant fails at each of three stages: compile error when the match isn't exhaustive, coverage failure when the sample is missing, validation failure when the schema branch is missing. Deleting the zoned branch fails 5 of 7 tests by name.

Every new guard was likewise reverted and confirmed to fail:

Still inexpressible, and now documented as such

Calendar validity (2026-04-31 matches the pattern; the reader rejects it), the representable instant range (9999-01-01 matches; it's an i64 nanosecond count), and tzdb membership. The description previously named an omission among these as if it were a limitation — corrected.

Also added: consumers must use a draft 2020-12 validator. Draft-07 silently no-ops prefixItems and drops all option-pair inner validation.

How to test

cargo test -p truecalc-workbook --test schema_value_variant_tests
cargo test -p truecalc-workbook --test sparkline_value_tests

To see the original bug: check out main, construct a workbook containing a TZNOW result, serialize it, and validate against crates/workbook/schema/workbook.v1.schema.json — it fails. On this branch it passes.

Review

• Independent review: 1 blocker + 4 findings, all fixed. The blocker was the schema being stricter than the reader on charttype — fix(workbook): the JSON schema is missing branches for non-scalar value variants #768 with the sign flipped, in the very branch added to fix fix(workbook): the JSON schema is missing branches for non-scalar value variants #768. The reviewer also verified purely-additive behaviourally (9 pre-existing and 6 previously-rejected shapes through both schema revisions, zero drift), reproduced all three test mutations, and probed 24 sparkline shapes finding reader/schema agreement on every one but the blocker.

Test plan

• cargo test --workspace — zero failures
• cargo clippy --workspace -- -D warnings — exit 0
• cargo nextest run --workspace --profile ci — exit 0
• Every new guard mutated and confirmed non-vacuous
• Pre-existing golden documents and the 256-case proptest pass unmodified
• CI green

Related

• SPARKLINE: implement the Google Sheets in-cell chart function #766 — SPARKLINE, whose wire form this makes canonical
• test(conformance): silently skipped rows assert nothing — 46 in text.tsv alone, and one pair passed for the wrong reason #767 — conformance rows that assert nothing

🤖 Generated with Claude Code

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}